Below is an example running coralseed using a dataset from Mermaid Bay, Lizard Island (nGBR), December 2022. The model simulates a point source release of 1000 particles from a 5*5m area within the site and tracks particles across a 6hr period.

1. Set seascape probability

First step is to generate a probabilistic habitat map for settlement. The seascape_probability function takes two shp files as inputs: 1) a map of reef substrates (merged classes of “coral/algae”, “rubble”, “rock” from the Allan Coral Atlas Benthic classes), and 2) a map of benthic habitat (e.g. “reef crest”, “reef slope” etc classes from geomorphic Allan Coral Atlas maps). The function generates a probability mosaic for settleable area (reef substrates) categorised by habitat types. Example reef_outline and habitat files are included for Lizard Island. To change the probabilities see ?settlement_probability.

library(coralseed)
library(ggplot2)
library(tidyverse)
library(sf)

seascape <- seascape_probability(reefoutline=reef_map, habitat=benthic_map)

2. Seed particles based on dispersal

coralseed works by i) simulate individual competency tracks for particles/larvae, ii) simulating larval mortality across a cohort, and iii) simulating settlement probability as particles/larvae pass over reef habitats. The seed_particles function does this by taking the input simulated particles, overlaying the probability seascape generated in step 1, and uses predict_competency and simulate_mortality to quantify competency and mortality respectively (see ?predict_competency and ?simulate_mortalityfor more details). The example below uses one of the included simulated particle tracks (“Mermaid_PointSource_Bay_01”) as inputand the seascape probability (seascape) generated in the previous step to track particles across a ~7hr period (limit_time). Mortality is set to 10% (simulate.mortality) and the shape of the mortality curve (simulate.mortality) is set to “typeI”. Settlement probability for particles passing over substrates (probability) is set to “additive” (see ?settle_particles) for further details.

seed_particles outputs summary statistics (set silent=FALSE) and summary plots of the main outputs (competency, mortality, spatial pattern (cartesian) and dispersaltime - set return.plot=TRUE to visualise these). Try changing the parameters and visualising the output.

The function returns an sf output in with spatial points for each individual particle (id) at 1 minute timesteps (dispersaltime) across trajectories and details the time in minutes when each particle becomes competent (settlement_point), the particle state (either 0 or 1) and competency (incompetent or competent), the benthic habitat it crosses at that point in time (class), unique habitat identifier (habitat_id) and settlement_probability for each habitat determined from the previous step, the settlement_outcome (i.e. was the particle competent AND probable to settle?), and finally the outcome (i.e. the transition between 0 and 1 is the final settlement point for a given particle).

coralseed can be run with either with inbuilt example datasets or input dispersal models in the format of .json files:

built-in example datasets

# example datasets: "mermaid", "watson", "spawnhub", "clamgarden", "palfrey"

particles <- seed_particles(example="watson", seascape=seascape,
                            competency.function = "exponential", set.seed=101,
                            limit.time=6, simulate.mortality = "typeI", 
                            simulate.mortality.n = 0.1, probability="additive",
                            silent=FALSE, return.plot=TRUE)

## ## coralseed model summary: #### 
## Importing 1000 particle tracks
## [No seed set, random draws used] 
## 
## Time start = 2022-12-16 14:00:00
## Time end = 2022-12-17 02:57:00
## Total dispersaltime (hrs) = 12.95
## Particle tracks limited to 6 hrs 
##   
## Competency at t6 = 214 / 1000 larvae 
## Competency at t12 = 385 / 1000 larvae 
## Competency at t24 = 643 / 1000 larvae 
##   
## Survivorship curve  
## Mortality at t6 = 6 / 1000 larvae 
## Mortality at t12 = 24 / 1000 larvae

json file inputs

sim1_1k <- readRDS("/Users/rof011/coralseed/code/run_day_12036_lizard_del_14_1512_sim1_1K_10.RDS")
particles <- seed_particles(input=sim1_1k, seascape=seascape,
                            competency.function = "exponential", set.seed=101,
                            limit.time=6, simulate.mortality = "typeI",
                            simulate.mortality.n = 0.1, probability="additive",
                            silent=FALSE, return.plot=TRUE)

## ## coralseed model summary: #### 
## Importing 1000 particle tracks
## [No seed set, random draws used] 
## 
## Time start = 2022-12-16
## Time end = 2022-12-17 00:57:00
## Total dispersaltime (hrs) = 1.03958333333333
## Particle tracks limited to 6 hrs 
##   
## Competency at t6 = 151 / 1000 larvae 
## Competency at t12 = 275 / 1000 larvae 
## Competency at t24 = 458 / 1000 larvae 
##   
## Survivorship curve  
## Mortality at t6 = 6 / 1000 larvae 
## Mortality at t12 = 24 / 1000 larvae

3. Settle particles based on probability

The settle_particles function takes the input from seed_particles and determines where along the settlement track each particle settles. As there's currently no data on how larvae settle and interact in the wild, the function adds three different possibilities: "additive" (if p=1 AND larvae are competent, larvae settle somewhere in that habitat along the particle trajectory), "lagged" (if p=1 AND larvae are competent, larvae settle somewhere in the habitat in the first 10 minutes, and "rapid" (if p=1 AND larvae are competent, larvae settle immediately once entering the habitat.

All larvae that are competent will settle somewhere in a habitat if p=1. "rapid" will produce unrealistic results as larvae will immediately settle on the borders of habitats. "lagged" is probably more realistic, but given that habitats are relatively small in size (seascapes are spatially complex) and most larvae pass through habitats fairly rapidly, either "lagged" or "additive" will produce fairly realistic results.

settlers <-  settle_particles(particles, probability="additive", silent=TRUE)

4. Map coralseed output

To spatially map all the above outputs, use the map_coralseed function. map_coralseed takes the outputs from steps 1 (seascape_probability), step 2 (seed_particles), and step 3 (settle_particles) as inputs and uses the tmap library to plot the shp files, particle tracks, and settlement points. The restoration.plot function takes a vector of width and length and draws a rectangular area over the centroid of the particle release.

map_output <- map_coralseed(seed_particles=particles, settle_particles=settlers, 
              seascape_probability=seascape, restoration.plot=c(100,100)) 

map_output